improvement(api): replace workflow jobs with execution resources by TheodoreSpeaks · Pull Request #6294 · simstudioai/sim

TheodoreSpeaks · 2026-08-05T20:19:29Z

Summary

replace public async workflow job receipts with execution IDs and canonical execution status resources
project queued initial and resumed runs through the execution endpoint until durable logs exist
remove the generic job route and update SDKs, OpenAPI, deployment examples, and localized references

Type of Change

Improvement
Breaking API cleanup

Testing

100 focused API tests
29 TypeScript SDK tests and SDK typecheck
28 Python SDK tests
OpenAPI validation, strict API validation, lint, and all repository audits
Full app typecheck still reports the existing Azure OpenAI and Gemini SDK type drift in untouched provider files

Checklist

Code follows project style guidelines
Self-reviewed my changes
Tests added/updated and passing
No new warnings introduced
I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

vercel · 2026-08-05T20:19:36Z

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Aug 5, 2026 10:34pm

cursor · 2026-08-05T20:21:37Z

PR Summary

High Risk
Breaking changes to the public execute/async contract and polling model affect all API and SDK integrations, though legacy endpoints are retained. Core execution, resume, and queue projection logic in shared paths increases regression risk.

Overview
Public workflow execution moves to v2: execute URLs become /api/v2/workflows/{id}/execute, bodies use input (not inputs) and async: true instead of X-Execution-Mode: async, and successful responses are wrapped in data. Async dispatch returns an execution ID and a v2 status URL rather than a separate job ID and /api/jobs/... polling.

Polling is unified on the execution resource: getWorkflowExecutionStatus now projects queued/running state from the async job queue (and resume queue) until durable logs exist, so v2 status routes no longer duplicate queue lookups. Trigger.dev enqueue tags runs with jobId: for deterministic lookup.

HITL resume adds POST /api/v2/workflows/{id}/executions/{executionId}/resume (body includes contextId), implemented via shared handleResumeExecution with surface-specific async receipts—legacy resume still exposes jobId and /api/jobs/.... Docs, OpenAPI, deploy-modal examples, copilot deploy helpers, and Python/TypeScript SDKs are aligned to v2 execute + getWorkflowExecution polling; legacy job status APIs remain documented as deprecated paths.

^{Reviewed by Cursor Bugbot for commit 94e28e7. Bugbot is set up for automated code reviews on this repo. Configure here.}

greptile-apps · 2026-08-05T20:23:30Z

Greptile Summary

The PR replaces public asynchronous workflow-job receipts with canonical execution resources while preserving legacy polling compatibility.

Adds execution-resource polling and a v2 human-in-the-loop resume endpoint.
Projects queued initial and resumed runs until durable execution logs become available.
Updates SDKs, contracts, OpenAPI specifications, deployment UI, examples, and documentation.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the previous resume-status issue is fixed by resolving active resume queue entries before the existing paused log, and the documentation convention thread was correctly resolved as inapplicable to external-consumer examples.

Important Files Changed

Filename	Overview
apps/sim/lib/workflows/executor/execution-status.ts	Projects claimed and pending resume attempts ahead of stale paused logs, with terminal durable logs retaining precedence.
apps/sim/app/api/resume/resume-handler.ts	Dispatches v2 async resumes with deterministic queue identities and returns canonical execution polling URLs while preserving legacy job receipts.
apps/sim/app/api/v2/workflows/[id]/executions/[executionId]/resume/route.ts	Adds the contract-bound v2 endpoint for resuming a paused workflow execution.
packages/ts-sdk/src/index.ts	Migrates SDK execution and polling behavior from generic jobs to canonical workflow execution resources.
packages/python-sdk/simstudio/init.py	Updates Python SDK async receipts and execution-status polling to use execution IDs.
apps/docs/openapi-v2-workflows.json	Documents the v2 resume endpoint and its synchronous, asynchronous, validation, and error responses.

Sequence Diagram

sequenceDiagram
  participant Client
  participant API as Workflow API
  participant Queue as Execution Queue
  participant Worker
  participant Logs as Durable Execution Logs
  Client->>API: POST execute/resume (async)
  API->>Queue: Enqueue using execution identity
  API-->>Client: 202 executionId + statusUrl
  Client->>API: GET execution resource
  API->>Queue: Resolve active queued attempt
  Queue-->>API: queued/running state
  API-->>Client: Execution resource
  Worker->>Logs: Persist execution state/output
  Client->>API: GET execution resource
  API->>Logs: Read durable state
  API-->>Client: completed/failed/paused resource

_{Reviews (6): Last reviewed commit: "fix(api): prefer terminal logs over stal..." | Re-trigger Greptile}

TheodoreSpeaks · 2026-08-05T21:11:07Z

@cursor review

TheodoreSpeaks · 2026-08-05T21:11:09Z

@greptile

TheodoreSpeaks · 2026-08-05T21:18:17Z

@greptile

TheodoreSpeaks · 2026-08-05T21:18:17Z

@cursor review

cursor

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 5698672. Configure here.}

TheodoreSpeaks · 2026-08-05T22:20:53Z

@greptile

TheodoreSpeaks · 2026-08-05T22:20:54Z

@cursor review

TheodoreSpeaks · 2026-08-05T22:29:03Z

@greptile

TheodoreSpeaks · 2026-08-05T22:29:04Z

@cursor review

cursor

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit c903ba1. Configure here.}

TheodoreSpeaks · 2026-08-05T22:34:32Z

@greptile

greptile-apps Bot reviewed Aug 5, 2026

View reviewed changes

Comment thread apps/sim/lib/workflows/executor/execution-status.ts Outdated

Comment thread apps/docs/content/docs/en/api-reference/typescript.mdx

vercel Bot deployed to Preview August 5, 2026 20:23 View deployment

cursor Bot reviewed Aug 5, 2026

View reviewed changes

Comment thread apps/sim/lib/workflows/executor/execution-status.ts Outdated

Comment thread apps/sim/lib/workflows/executor/execution-status.ts Outdated

TheodoreSpeaks force-pushed the codex/remove-workflow-job-api branch from 3dcbfe2 to 3313651 Compare August 5, 2026 20:56

vercel Bot deployed to Preview August 5, 2026 21:01 View deployment

cursor Bot reviewed Aug 5, 2026

View reviewed changes

Comment thread ...orkflowId]/components/panel/components/deploy/components/deploy-modal/components/api/api.tsx

vercel Bot temporarily deployed to Preview August 5, 2026 21:07 Inactive

vercel Bot temporarily deployed to Preview August 5, 2026 21:09 Inactive

cursor Bot reviewed Aug 5, 2026

View reviewed changes

Comment thread apps/sim/lib/workflows/executor/execution-status.ts

vercel Bot temporarily deployed to Preview August 5, 2026 21:17 Inactive

cursor Bot reviewed Aug 5, 2026

View reviewed changes

TheodoreSpeaks added 6 commits August 5, 2026 15:19

improvement(api): replace workflow jobs with execution resources

d53bd51

fix(api): preserve legacy jobs while preferring v2 executions

6236bb2

fix(api): make execution polling resume-aware

8e2c0b9

fix(ui): hide async examples for public workflows

460a11e

fix(api): bridge resume queue visibility lag

af162f8

feat(api): add v2 workflow resume endpoint

a4c1152

TheodoreSpeaks force-pushed the codex/remove-workflow-job-api branch from 5698672 to a4c1152 Compare August 5, 2026 22:20

cursor Bot reviewed Aug 5, 2026

View reviewed changes

Comment thread apps/sim/lib/workflows/executor/execution-status.ts

Comment thread ...orkflowId]/components/panel/components/deploy/components/deploy-modal/components/api/api.tsx

vercel Bot deployed to Preview August 5, 2026 22:25 View deployment

fix(api): project pending resume attempts

c903ba1

vercel Bot temporarily deployed to Preview August 5, 2026 22:28 Inactive

cursor Bot reviewed Aug 5, 2026

View reviewed changes

Comment thread apps/sim/lib/workflows/executor/execution-status.ts

fix(api): prefer terminal logs over stale resumes

94e28e7

vercel Bot temporarily deployed to Preview August 5, 2026 22:34 Inactive

TheodoreSpeaks merged commit f32dc83 into improvement/v2-endpoints Aug 5, 2026
5 checks passed

TheodoreSpeaks deleted the codex/remove-workflow-job-api branch August 5, 2026 23:25

Uh oh!

Conversation

TheodoreSpeaks commented Aug 5, 2026

Summary

Type of Change

Testing

Checklist

Uh oh!

vercel Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cursor Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

greptile-apps Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Sequence Diagram

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

TheodoreSpeaks commented Aug 5, 2026

Uh oh!

TheodoreSpeaks commented Aug 5, 2026

Uh oh!

Uh oh!

TheodoreSpeaks commented Aug 5, 2026

Uh oh!

TheodoreSpeaks commented Aug 5, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

TheodoreSpeaks commented Aug 5, 2026

Uh oh!

TheodoreSpeaks commented Aug 5, 2026

Uh oh!

Uh oh!

Uh oh!

TheodoreSpeaks commented Aug 5, 2026

Uh oh!

TheodoreSpeaks commented Aug 5, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

TheodoreSpeaks commented Aug 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

vercel Bot commented Aug 5, 2026 •

edited

Loading

cursor Bot commented Aug 5, 2026 •

edited

Loading

greptile-apps Bot commented Aug 5, 2026 •

edited

Loading